.TH "dcmrecv" 1 "Mon Oct 28 2019" "Version 3.6.5" "OFFIS DCMTK" \" -*- nroff -*-
.nh
.SH NAME
dcmrecv \- Simple DICOM storage SCP (receiver)

.SH "SYNOPSIS"
.PP
.PP
.nf
dcmrecv [options] port
.fi
.PP
.SH "DESCRIPTION"
.PP
The \fBdcmrecv\fP application implements a Service Class Provider (SCP) for the Storage Service Class\&. In contrast to the well-known \fBstorescp\fP utility, \fBdcmrecv\fP has less options and might, therefore, be easier to use - this also explains the term 'simple' in the title\&. The main purpose of this application is to receive a whole bunch of DICOM datasets from a Storage Service Class User (SCU) and store them to a configurable directory and file structure\&.
.SH "PARAMETERS"
.PP
.PP
.nf
port  tcp/ip port number to listen on
.fi
.PP
.SH "OPTIONS"
.PP
.SS "general options"
.PP
.nf
  -h    --help
          print this help text and exit

        --version
          print version information and exit

        --arguments
          print expanded command line arguments

  -q    --quiet
          quiet mode, print no warnings and errors

  -v    --verbose
          verbose mode, print processing details

  -d    --debug
          debug mode, print debug information

  -ll   --log-level  [l]evel: string constant
          (fatal, error, warn, info, debug, trace)
          use level l for the logger

  -lc   --log-config  [f]ilename: string
          use config file f for the logger

  +v    --verbose-pc
          show presentation contexts in verbose mode
.fi
.PP
.SS "network options"
.PP
.nf
association negotiation profile from configuration file:

  -xf   --config-file  [f]ilename, [p]rofile: string
          use profile p from configuration file f

application entity title:

  -aet  --aetitle  [a]etitle: string
          set my AE title (default: DCMRECV)

  -uca  --use-called-aetitle
          always respond with called AE title

other network options:

  -ta   --acse-timeout  [s]econds: integer (default: 30)
          timeout for ACSE messages

  -td   --dimse-timeout  [s]econds: integer (default: unlimited)
          timeout for DIMSE messages

  -pdu  --max-pdu  [n]umber of bytes: integer (4096..131072)
          set max receive pdu to n bytes (default: 16384)

  -dhl  --disable-host-lookup  disable hostname lookup
.fi
.PP
.SS "output options"
.PP
.nf
general:

  -od   --output-directory  [d]irectory: string (default: ".")
          write received objects to existing directory d

subdirectory generation:

  -s    --no-subdir
          do not generate any subdirectories (default)

  +ssd  --series-date-subdir
          generate subdirectories from series date

filename generation:

  +fd   --default-filenames
          generate filename from instance UID (default)

  +fu   --unique-filenames
          generate unique filename based on new UID

  +fsu  --short-unique-names
          generate short pseudo-random unique filename

  +fst  --system-time-names
          generate filename from current system time

  -fe   --filename-extension  [e]xtension: string (default: none)
          append e to all generated filenames

storage mode:

  -B    --normal
          allow implicit format conversions (default)

  +B    --bit-preserving
          write dataset exactly as received

        --ignore
          ignore dataset, receive but do not store it
.fi
.PP
.SH "NOTES"
.PP
.SS "Typical Usage"
A typical use case of \fBdcmrecv\fP is to receive SOP instances that are sent from a storage SCU and save them as DICOM files\&. The following command does exactly this:
.PP
.PP
.nf
dcmrecv --verbose <port> --config-file storescp.cfg default
.fi
.PP
.PP
If you prefer some automatically created subdirectory structure, shorter file names and the extension '\&.dcm' for all DICOM files, use the following command:
.PP
.PP
.nf
dcmrecv -v -xf storescp.cfg default <port> --series-date-subdir
                                           --short-unique-names
                                           --filename-extension .dcm
.fi
.PP
.PP
In case of very large SOP instances or if the dataset should be written exactly as received (e\&.g\&. for debugging purposes), the 'bit preserving mode' could be used:
.PP
.PP
.nf
dcmrecv -v -xf storescp.cfg default <port> --bit-preserving
.fi
.PP
.PP
The received datasets are always stored as DICOM files with the same Transfer Syntax as used for the network transmission\&.
.SS "DICOM Conformance"
Basically, the \fBdcmrecv\fP application supports all Storage SOP Classes as an SCP, including private ones\&. This requires, however, that a corresponding association negotiation profile is loaded from a configuration file\&. The format and semantics of this configuration file are documented in \fIasconfig\&.txt\fP\&.
.PP
By default, that means if no association negotiation profile is loaded, \fBdcmrecv\fP only supports the Verification SOP Class as an SCP (with default transfer syntax, i\&.e\&. Implicit VR Litte Endian)\&.
.PP
In the future, there might be additional options that allow for specifying the list of supported Presentation Contexts (i\&.e\&. combination of SOP Class and Transfer Syntaxes) directly, i\&.e\&. without loading a configuration file\&.
.SS "Subdirectory Generation"
The option \fI--series-date-subdir\fP allows for generating subdirectories (below the specified output directory) based on the value of the data element Series Date (0008,0021) from the received DICOM dataset\&. If this value could be retrieved from the dataset and is valid (i\&.e\&. consists of a valid DICOM date field), the subdirectory structure is as follows:
.PP
.PP
.nf
<output-directory>/data/<year>/<month>/<day>/<filename>
.fi
.PP
.PP
If the Series Date (0008,0021) cannot be retrieved or is invalid, the current system date is used for the following subdirectory structure:
.PP
.PP
.nf
<output-directory>/undef/<year><month><day>/<filename>
.fi
.PP
.PP
In both cases, <year> consists of 4 decimal digits and <month> as well as <day> of 2 decimal digits\&.
.SS "Filename Generation"
By default, the filenames for storing the received DICOM datasets are generated according to the following scheme:
.PP
.PP
.nf
<short-modality-prefix>.<sop-instance-uid><filename-extension>
.fi
.PP
.PP
If the same SOP instance is received twice, a warning message is reported and the existing file is overwritten\&.
.PP
The option \fI--unique-filenames\fP makes sure that each received DICOM dataset is stored as a separate file, i\&.e\&. no files should ever be overwritten\&. This is done by using a newly created unique identifier (UID) for each generated filename (and the infix '\&.X' in order to avoid conflicts with real SOP Instance UID values)\&. The naming scheme for this option is as follows:
.PP
.PP
.nf
<short-modality-prefix>.X.<unique-identifier><filename-extension>
.fi
.PP
.PP
When option \fI--short-unique-names\fP is used, the filenames are generated by some pseudo-random name generator, which also makes sure that there are no conflicts (i\&.e\&. existing files are not overwritten)\&. This is the naming scheme:
.PP
.PP
.nf
<short-modality-prefix>_<pseudo-random-name><filename-extension>
.fi
.PP
.PP
With <pseudo-random-name> consisting of 16 digits in hexadecimal notation\&.
.PP
Finally, option \fI--system-time-names\fP allows for generating filenames based on the current system time:
.PP
.PP
.nf
<date><time>.<short-modality-prefix><filename-extension>
.fi
.PP
.PP
With <date> consisting of '<year><month><day>' and <time> of '<hour><minute><second>\&.<micro-second>'\&. Please note that this scheme could result in naming conflicts if the resolution of the system time is not sufficiently high (i\&.e\&. does not support microseconds)\&.
.SS "Limitations"
Please note that option \fI--bit-preserving\fP cannot be used together with option \fI--series-date-subdir\fP since the received dataset is stored directly to file and the value of the Series Date (0008,0021) is, therefore, not available before the file has been created\&.
.SH "LOGGING"
.PP
The level of logging output of the various command line tools and underlying libraries can be specified by the user\&. By default, only errors and warnings are written to the standard error stream\&. Using option \fI--verbose\fP also informational messages like processing details are reported\&. Option \fI--debug\fP can be used to get more details on the internal activity, e\&.g\&. for debugging purposes\&. Other logging levels can be selected using option \fI--log-level\fP\&. In \fI--quiet\fP mode only fatal errors are reported\&. In such very severe error events, the application will usually terminate\&. For more details on the different logging levels, see documentation of module 'oflog'\&.
.PP
In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option \fI--log-config\fP can be used\&. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated\&. An example configuration file is provided in \fI<etcdir>/logger\&.cfg\fP\&.
.SH "COMMAND LINE"
.PP
All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values\&.
.PP
Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively\&. Usually, order and position of command line options are arbitrary (i\&.e\&. they can appear anywhere)\&. However, if options are mutually exclusive the rightmost appearance is used\&. This behavior conforms to the standard evaluation rules of common Unix shells\&.
.PP
In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e\&.g\&. \fI@command\&.txt\fP)\&. Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation\&. Please note that a command file cannot contain another command file\&. This simple but effective approach allows one to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file \fI<datadir>/dumppat\&.txt\fP)\&.
.SH "EXIT CODES"
.PP
The \fBdcmrecv\fP utility uses the following exit codes when terminating\&. This enables the user to check for the reason why the application terminated\&.
.SS "general"
.PP
.nf
EXITCODE_NO_ERROR                         0
EXITCODE_COMMANDLINE_SYNTAX_ERROR         1
.fi
.PP
.SS "input file errors"
.PP
.nf
EXITCODE_CANNOT_READ_INPUT_FILE          20 (*)
.fi
.PP
.SS "output file errors"
.PP
.nf
EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40 (*)
EXITCODE_INVALID_OUTPUT_DIRECTORY        45
.fi
.PP
.SS "network errors"
.PP
.nf
EXITCODE_CANNOT_INITIALIZE_NETWORK       60 (*)
EXITCODE_CANNOT_START_SCP_AND_LISTEN     64
EXITCODE_INVALID_ASSOCIATION_CONFIG      66
.fi
.PP
.PP
(*) Actually, these codes are currently not used by \fBdcmrecv\fP but serve as a placeholder for the corresponding group of exit codes\&.
.SH "ENVIRONMENT"
.PP
The \fBdcmrecv\fP utility will attempt to load DICOM data dictionaries specified in the \fIDCMDICTPATH\fP environment variable\&. By default, i\&.e\&. if the \fIDCMDICTPATH\fP environment variable is not set, the file \fI<datadir>/dicom\&.dic\fP will be loaded unless the dictionary is built into the application (default for Windows)\&.
.PP
The default behavior should be preferred and the \fIDCMDICTPATH\fP environment variable only used when alternative data dictionaries are required\&. The \fIDCMDICTPATH\fP environment variable has the same format as the Unix shell \fIPATH\fP variable in that a colon (':') separates entries\&. On Windows systems, a semicolon (';') is used as a separator\&. The data dictionary code will attempt to load each file specified in the \fIDCMDICTPATH\fP environment variable\&. It is an error if no data dictionary can be loaded\&.
.SH "FILES"
.PP
\fI<docdir>/asconfig\&.txt\fP - configuration file documentation
.br
\fI<etcdir>/storescp\&.cfg\fP - example association negotiation profile
.SH "SEE ALSO"
.PP
\fBdcmsend\fP(1), \fBstorescu\fP(1), \fBstorescp\fP(1)
.SH "COPYRIGHT"
.PP
Copyright (C) 2013-2017 by OFFIS e\&.V\&., Escherweg 2, 26121 Oldenburg, Germany\&.
